; -*- Mode: text -*-

;;; File:  AutoClass:doc;reports.text
;;;--------------------------------------------------------------------------;;;
;;;  AUTOCLASS 3.0  Released 5/11/90    contact:  Taylor@pluto.arc.nasa.gov  ;;;
;;;  by P. Cheeseman, J. Stutz, R. Hanson, W. Taylor 			     ;;;
;;;  NASA Ames Research Center, MS 244-17, Moffett Field, CA 94035           ;;;
;;;                                                                          ;;;
;;;  Copyright (C) 1990 Research Institute for Advanced Computer Science.    ;;;
;;;  All rights reserved.  The RIACS Software Policy contains specific       ;;;
;;;  terms and conditions on the use of this software, and must be           ;;;
;;;  distributed with any copies.  THIS FILE MAY BE REDISTRIBUTED.  This     ;;;
;;;  copyright and notice must be preserved in all copies made of this file. ;;;
;;;--------------------------------------------------------------------------;;;



			GENERATING REPORTS


You are provided two functions for outputting the three standard reports from the
results generated by AUTOCLASS-SEARCH. The functions are 
AUTOCLASS-REPORTS-FROM-CLSF and AUTOCLASS-REPORTS-FROM-RESULTS-FILE. The 
standard reports are 

	1) attribute influence values: presents the relative influence or 
	   significance of the data's attributes both globally (averaged over
	   all classes), and locally (specifically for each class). A heuristic
	   for relative class strength is also listed;
	2) cross-reference by case (datum) number: lists the primary class 
	   probability for each datum, ordered by case number;
	3) cross-reference by class number: for each class the primary class
	   probability and any lesser class probabilities (greater than 0.10)
	   are listed for each datum in the class, ordered by case number. It
	   is also possible to list, for each datum, the values of attributes, 
	   which you select.

The attribute influence values report attempts to provide relative measures of
the "influence" of the data attributes on the classes found by the classification.
The normalized class strengths, the normalized attribute influence values summed
over all classes, and the individual influence values (I[jkl]) are all only 
relative measures and should be interpreted with more meaning than rank ordering,
but not like anything approaching absolute values.

The reports are output to files whose pathnames are "merged" onto that of the
results-file argument (in the case of AUTOCLASS-REPORTS-FROM-RESULTS-FILE), 
for example --

	(autoclass-reports-from-results-file
	  "autoclass-x:>data>soybean>soy&soy&soy" .... )

or the pathname of :stream-or-reports-pathname (in the case of                     
AUTOCLASS-REPORTS-FROM-CLSF, when its value is a pathname), for example --

	(autoclass-reports-from-clsf <clsf>
	  "autoclass-x:>data>soybean>soy&soy&soy" ..... 
produces

	"autoclass-x:>data>soybean>soy&soy&soy.influ-text" , etc.

The report file types (extensions) are:

	influence values report:  "influ-text"  & "influ-data"
	cross-reference by case:  "case-text"   & "case-data"
	cross-reference by class: "class-text"  & "class-data"

The report generator functions, by default (:report-type :text) produce 
formatted reports (file type of "xxxx-text"). However, with :report-type 
specified as :data or :both, they will produce list data structures of the 
appropriate information, such that you can write individually tailored
report formatters (file type of "xxxx-data"). Both these functions return
the classification structure.

The input argument list of AUTOCLASS-REPORTS-FROM-CLSF is:

	(clsf stream-or-reports-pathname
	 &key (report-type :all)
	      (report-mode :text) (package *ac-pkg*)
	      (num-atts-to-list :all) (results-file "")
              (xref-class-report-att-list '())
	      (i-v-header-label-fcn #'influence-values-header-label)
	      (title-font-fcn #'default-title-font-fcn) .. )

The required arguments are: 

:CLSF, a classification structure (type classification-$) which is contained
	in the second return value of AUTOCLASS-SEARCH (the vector of best
	classifications); and 
:STREAM-OR-REPORTS-PATHNAME, which can be an output stream (e.g. 
	*standard-output*) or a fully qualified pathname.

The :REPORT-TYPE keyword argument can be any one of:

    value		influence values   xref by case   xref by class
    -----		----------------   ------------   -------------
    :all			x		x		x	 
    :influence-values		x
    :xref-case					x
    :xref-class							x
    :influ&x-case		x		x
    :influ&x-class		x				x
    :x-case&x-class				x		x

Other keyword arguments are:

:REPORT-MODE, which can be :both, :text, or :data;
:NUM-ATTS-TO-LIST, which should be an integer number of attributes to list in
	the influence value report (the default is :all); 
:RESULTS-FILE, used to document the results file with which this classification
	is associated (its existence is verified by the program); 
:XREF-CLASS-REPORT-ATT-LIST, a list of attribute numbers, which will cause 
	their values to be output along with the case numbers in the cross-
	reference by class output (see sample report); and 
:I-V-HEADER-LABEL-FCN & :TITLE-FONT-FCN, which allow you to write your own host
	specific functions for the influence value report header labels and the
	titles for all reports.

The input argument list of AUTOCLASS-REPORTS-FROM-RESULTS-FILE is:

	(results-file 
	 &key (report-type :all) (report-mode :text)
	      (reports-pathname :results-file)
	      (num-atts-to-list :all) (package *ac-pkg*)
	      (xref-class-report-att-list '())
	      (i-v-header-label-fcn #'influence-values-header-label)
	      (title-font-fcn #'default-title-font-fcn) ... )

The only required argument is RESULTS-FILE, the fully qualified pathname of the
results file, but without a file type since the program will determine for you 
whether the file type is "results" (*clsf-ASCII-results-file-type*) or "dump"
(*clsf-compiled-dump-file-type*).

A new keyword argument, not already presented is :REPORTS-PATHNAME, which allows
you the option of directing the report output to a specified pathname of your 
choice. 

See sample reports in directory ....>autoclass>sample>:    
                                                                 
	"imports-85&imports-85&imports-85.influ-text"
	"imports-85&imports-85&imports-85.case-text"
	"imports-85&imports-85&imports-85.class-text"

which were generated by the form:

	(autoclass-reports-from-results-file
  	  "<host>: .... >autoclass>sample>imports-85&imports-85&imports-85"     
  	  :xref-class-report-att-list '(2 5 6))



-------------------------------------------------------------------------------
-------------------------------------------------------------------------------
